Arrays/ArrayDeclarationSpacing: add new property and soft-deprecate old one by rodrigoprimo · Pull Request #2696 · WordPress/WordPress-Coding-Standards

rodrigoprimo · 2026-02-06T15:09:03Z

Description

Adds a new allow_single_item_single_line_explicit_key_arrays property to the WordPress.Arrays.ArrayDeclarationSpacing sniff and soft-deprecates the old allow_single_item_single_line_associative_arrays property to align the property name with the "explicit keys" terminology introduced in #2688.

For now, the old property continues to work via a backward compatibility layer: if the new property has not been changed from its default value and the old property has, the old property's value is used. The plan is to remove the old property in the next major release.

This is a soft deprecation (docblock and changelog only) as suggested in #2691 (comment). We are considering adding a runtime deprecation warning in the last release before the next major.

Besides that, this PR includes a separate commit that moves an intentional parse error test to its own file.

Suggested changelog entry

Deprecated

WordPress.Arrays.ArrayDeclarationSpacing: the allow_single_item_single_line_associative_arrays property has been deprecated in favor of allow_single_item_single_line_explicit_key_arrays.

Additional notes

If this PR is merged:

https://github.com/WordPress/WordPress-Coding-Standards/wiki/Customizable-sniff-properties should be updated to document the new property name.
I suggest creating an issue to centralize everything that needs to be addressed in the last release before 4.0, starting with hard-deprecating allow_single_item_single_line_associative_arrays.

Related issues/external references

Closes: #2691

jrfnl

Hi @rodrigoprimo,

Thanks for working on this. This looks good to me, aside from some nitpicking.

Besides that, this PR includes a separate commit that moves an intentional parse error test to its own file.

I understand why you made that change in this PR, but that change has a different decision point, so could have been merged already if pulled separately (ahead of this change).

I suggest creating an issue to centralize everything that needs to be addressed in the last release before 4.0, starting with hard-deprecating this allow_single_item_single_line_associative_arrays.

I'd suggest creating two new issues:

To hard-deprecate the old property in the last WPCS 3.x release (also see my notes about how to do this in #2691)
To remove the old property in WPCS 4.0.

jrfnl · 2026-02-23T15:14:13Z

+	 *
+	 * @var bool Defaults to true.
+	 */
+	public $allow_single_item_single_line_explicit_key_arrays = true;


I'm trying to think of a shorter name which is still descriptive enough and failing.

@GaryJones @dingo-d Have either of you got any suggestions ?

If not, I'm okay with leaving it at what it currently is. Just feels clunky and if we do want to change the name, now would be the time.

Let's leave it as is. There are alternatives, but I'm not convinced by any of them for various reasons.

rodrigoprimo · 2026-02-23T20:01:36Z

Thanks for your review, @jrfnl! I addressed the points that you raised.

I'd suggest creating two new issues:

To hard-deprecate the old property in the last WPCS 3.x release (also see my notes about how to do this in Arrays/ArrayDeclarationSpacing: how to deprecate the allow_single_item_single_line_associative_arrays property? #2691)

To remove the old property in WPCS 4.0.

I agree with your proposal to create two different issues.

My original plan was to create a generic issue where we can track everything that needs to be hard-deprecated in the last WPCS 3.x release (for now, only the property soft-deprecated in this PR, AFAIK) instead of creating an issue just for this property. Similarly, I would then create an issue to track everything that needs to be removed in the WPCS 4.0 release, and not an issue just to remove this one property. Does this approach make sense? I'm asking because it's not clear to me from your comment whether you prefer two specific issues just for allow_single_item_single_line_associative_arrays, or if the broader approach I have in mind is fine.

jrfnl · 2026-02-23T22:56:05Z

it's not clear to me from your comment whether you prefer two specific issues just for allow_single_item_single_line_associative_arrays, or if the broader approach I have in mind is fine.

From a maintainer point of view, I don't have a strong preference either way (as I'd always have to open the tickets anyway to make sure the right thing gets addressed).

From an end-user point of view, I think I'd prefer separate issues for separate deprecations/removals as that way when looking at the 4.0 milestone, I could just "scan the headlines" to get a quick overview of what to expect instead of having to open the issue and dig into the fine print to figure out what will change.

Does that help ?

jrfnl

Save for the discussion regarding a potential namespace for the new property as per #2696 (comment), I'm happy with this PR.

…ld one Add `allow_single_item_single_line_explicit_key_arrays` property to replace `allow_single_item_single_line_associative_arrays`, aligning the property name with the "explicit keys" terminology from PR 2688. The old property is soft-deprecated (docblock only) and continues to work via a backward compatibility layer: if the new property has not been changed from its default and the old property has with a valid value, the old property's value is used. Closes: 2691 Co-authored-by: Juliette <663378+jrfnl@users.noreply.github.com>

rodrigoprimo · 2026-02-24T15:15:48Z

Squashed the review changes into the original commit and force-pushed.

jrfnl · 2026-02-24T17:41:08Z

FYI: In light of this PR now having been merged, I've re-milestoned everything merged so far from the 3.3.x milestone to the 3.4.0 milestone, as the introduction of a new property and deprecation of another belong in a minor, not a patch version.

rodrigoprimo · 2026-02-25T13:51:42Z

Just documenting that I created the two follow-up issues to hard-deprecate and then remove the old property (#2704 and #2705).

Regarding updating the wiki with the new property name once 3.4.0 is released, do you think the note in the release checklist to check whether the wiki needs updating is sufficient?

jrfnl · 2026-02-25T14:17:15Z

@rodrigoprimo Feel free to update the wiki already. That should ensure we don't forget (and the "Available since" info should prevent confusion for end-users anyway).

rodrigoprimo · 2026-02-25T14:45:19Z

Done, thanks!

jrfnl · 2026-02-25T14:52:13Z

Done, thanks!

@rodrigoprimo Uh..oh .... you seem to have removed the old property from the table. This is wrong as it means that people on an older version of WPCS can no longer find the information they need about the old property.

The docs should contain both the info about the old + the new property, with annotations about when each were added and when the first was deprecated.
The information about the "old" property should only be removed once WPCS 5.0.0 comes out.

rodrigoprimo · 2026-02-25T19:02:27Z

I removed the information about the old property from the table, but added a note to document its deprecation. I did not consider that in the wiki we want to keep information for users of older versions of WPCS. I have made a new update, adding the old property back to the wiki. Let me know if it looks good now.

jrfnl · 2026-02-25T19:35:31Z

I removed the information about the old property from the table, but added a note to document its deprecation. I did not consider that in the wiki we want to keep information for users of older versions of WPCS. I have made a new update, adding the old property back to the wiki. Let me know if it looks good now.

@rodrigoprimo Thanks for that. I've tweaked the section a little more to be more in line with other property renames, which are annotated throughout the page.

rodrigoprimo added Type: Enhancement Status: Review ready Component: Core labels Feb 6, 2026

Arrays/ArrayDeclarationSpacing: move parse error test to its own file

03a96ee

rodrigoprimo force-pushed the array-declaration-spacing-new-property branch from c02099d to a0b04f6 Compare February 6, 2026 15:11

jrfnl reviewed Feb 23, 2026

View reviewed changes

rodrigoprimo force-pushed the array-declaration-spacing-new-property branch from eb902f9 to 083ad26 Compare February 23, 2026 19:46

jrfnl approved these changes Feb 23, 2026

View reviewed changes

jrfnl added this to the 3.4.0 milestone Feb 23, 2026

rodrigoprimo force-pushed the array-declaration-spacing-new-property branch from 083ad26 to 2229662 Compare February 24, 2026 15:14

GaryJones approved these changes Feb 24, 2026

View reviewed changes

GaryJones merged commit 9126fa1 into WordPress:develop Feb 24, 2026
31 checks passed

github-actions Bot removed the Status: Review ready label Feb 24, 2026

rodrigoprimo deleted the array-declaration-spacing-new-property branch February 25, 2026 12:22

Uh oh!

Conversation

rodrigoprimo commented Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Suggested changelog entry

Deprecated

Additional notes

Related issues/external references

Uh oh!

jrfnl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jrfnl Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

GaryJones Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

rodrigoprimo commented Feb 23, 2026

Uh oh!

jrfnl commented Feb 23, 2026

Uh oh!

jrfnl left a comment

Choose a reason for hiding this comment

Uh oh!

rodrigoprimo commented Feb 24, 2026

Uh oh!

Uh oh!

jrfnl commented Feb 24, 2026

Uh oh!

rodrigoprimo commented Feb 25, 2026

Uh oh!

jrfnl commented Feb 25, 2026

Uh oh!

rodrigoprimo commented Feb 25, 2026

Uh oh!

jrfnl commented Feb 25, 2026

Uh oh!

rodrigoprimo commented Feb 25, 2026

Uh oh!

jrfnl commented Feb 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rodrigoprimo commented Feb 6, 2026 •

edited

Loading